List Navigator
Description
If enabled, the List Navigator shows values from the Group Header in a List Control. A List Navigator can only be added to a List with server-side and/or client-side group breaks.
Discussion
When you have a lot of records in a List, scrolling the List to the bring a section of the List into view can be tedious - especially on mobile devices where there is no vertical scroll bar. The List Navigator makes it easy to scroll a List that has group breaks. In the image below a List is shown with group breaks on the first character of the Contactname field. A List Navigator is shown on the right side of the List.
The user can drag on the Navigator to quickly scroll the List.
The Navigator has an entry for each Group Heading.
The Navigator can be positioned on the left, right, top or bottom of the List. Positioning the Navigator on the top or bottom is generally done when the List is set to scroll horizontally.
You have complete control over the size of the Navigator (when it is not in use) and its position (relative to to the edge of the List). The size of the Navigator when it is in use (i.e. when the user is dragging on it), is automatically determined by its contents. If the size of the Navigator (when it is not in use) is not wide enough (for left/right position), or high enough (for top/bottom position) to show its full contents when the user starts to drag on it, it will dynamically resize while it is in use and then go back to the smaller size when the user stops dragging on it.
To define a Navigator for a List, check the Has List Navigator property on the List Properties pane of the List Builder. Then click the smart field to open the genie.
The List Navigator builder (shown above) allows you to define a JavaScript expression that determines what data are put into the Navigator. You expression can reference the special html variable. The html variable contains the HTML that is shown in the Group Header.
In the above screen show, the HTML expression is:
html
This means that if the Group Headers in the List contain capital letters A through Z:
A B C D ...
The Navigator will also contain the exact same values.
But, if the HTML expression was:
html.toLowerCase()
The Navigator would contain lowercase values a through z:
a b c d ...
Properties
The following properties are used to configure the List Navigator:
Has List Navigator
Check to enable the List Navigator. The List Navigator can only be added to a List control with server-side or client-side group breaks.
List Navigator definition
This property is exposed when the Has List Navigator property has been checked.
The List Navigator definition defines the look and feel of the List Navigator, including the text shown in, the location of, and optional styling applied to the navigator.
HTML expression
Specify a JavaScript expression that returns the HTML shown in the Navigator for each Group Break in the List. The List Navigator HTML expression is evaluated for each Group Header.
By default, all HTML shown in the Group Header is included in the List Navigator. The HTML expression can be modified to return any value. For example, if you only wanted to include the first character of the Group Header HTML, you could enter the following expression:
html.substr(0,1)
The html variable contains the HTML markup for the current Group Header.
Navigator classname
Specify an optional CSS class name for the Navigator. The class can be an explicit CSS class name or a CSS class name placeholder.
Navigator focus classname
Specify an optional CSS class name for the Navigator when it has focus (i.e. it is 'in use' - the user is dragging on it).. The class can be an explicit CSS class name or a CSS class name placeholder.
Navigator style
Specify an in-line style for the Navigator.
Position
Specify where the Navigator should be positioned. Choices include right, left, top, or bottom.
Offset
Specify the offset in pixels. This is the distance from the edge of the List (top, bottom, left or right edge - depending on the specified setting for Position) to the outer edge of the Navigator. The default offset is 4.
Size
Specify the size in pixels of the Navigator when it is not 'in-use' (i.e. the user is not dragging on it). Default is 20. Set to -1 for 'as big as needed' (so that all of the text from each Group Header can be shown in full). When the Navigator is 'in-use' it automatically expands in size so that all entries can be seen in full.
Videos
Client-side Grouping and List Navigator
Group breaks can be inserted into the List control. The group breaks can be 'server-side' group breaks, or 'client-side' group breaks. The advantage of 'client-side' group breaks is that they can be dynamically applied to the data in the List. That means you can easily switch from grouping the data by 'Lastname' to grouping by 'City', etc. You can also display summary values in the group headers and footer.
For lists that have group breaks (regardless of whether the group breaks were computed server-side or client-side), you can also display a List Navigator, which allows the user to easily scroll a long List.
In this video we give an overview of client-side group breaks and the List Navigator. Then, we go into depth on setting up client-side grouping using Action Javascript (to apply the group breaks after the List is initially rendered) and in the List definition itself (so that when the List is initially rendered, the group breaks are shown).
We also show how summary data can be inserted into a List header or footer.
See Also